<style>
    body  {font-family: verdana;}
</style>
<p>
	Everyone loves client side templates. 
	They are a great way to create html 
	which is something JavaScript apps do all the time.
</p> 

<p>In February, a jQuery templating system was 
<a href='http://github.com/nje/jquery/wiki/jquery-templates-proposal'>proposed<a/> and resulted in a tremendous amount of 
<a href='http://forum.jquery.com/topic/jquery-templates-proposal'>discussion</a>, followed by an 
official templating engine for jQuery - <a href='http://www.borismoore.com/2010/10/jquery-templates-is-now-official-jquery.html'>jquery-tmpl</a>.
</p> 

<p>
Although jquery-tmpl is a solid templating engine, 
the discussion highlighted three 
extremely important facts about developers and client side templates:
</p> 

<h4>
Fact 1: Everyone has their favorite templating engine
</h4> 

<p>
There's a whole slew of templating languages people like:
</p> 

<ul>
	<li><a href='http://EmbeddedJS.com'>EmbeddedJS</a></li>
	<li><a href='http://code.google.com/p/trimpath/wiki/JavaScriptTemplates'>TrimJunction's JavaScript Templates</a></li>
	<li><a href='http://github.com/edspencer/jaml'>Jaml</a></li>
	<li><a href='http://github.com/jquery/jquery-tmpl'>jquery-tmpl</a></li>
	<li><a href='http://github.com/janl/mustache.js/'>mustache</a></li>
	<li><a href='http://ejohn.org/blog/javascript-micro-templating/'>micro</a></li>
	<li><a href='http://github.com/raid-ox/chain.js/wiki'>chain.js</a></li>  
</ul> 

<p>
Most of these template engines have distinct advantages and dissadvantages.
It's impossible to expect a single template engine to meet everyone's needs.
</p> 
<h4>Fact 2: Most templating engines provide the exact same features</h4>
<p>
	I've yet to encounter a template that does't provide:
</p>
<ul>
	<li>A way of loading templates (typically from HTMLElement or files)</li>
	<li>A way of caching processed templates.</li>
	<li>An interface to render the template with arbitrary data.</li>
</ul>
<h4>Fact 3: Very few people are familiar with 
the complexities of using templates</h4>
<p>There's more than just syntax and magic tag preference that goes
into a templating system.  Consider:</p>
<ul>
	<li>How can I build and share plugins that uses templates?</li>
	<li>How can I share templates across pages / apps?</li>
	<li>How can I organize template files?</li>
</ul>
<h2>jQuery.View</h2>

<p>
<a href='http://v3.javascriptmvc.com/index.html#&who=jQuery.View'>jQuery.View</a> 
is a templating interface that takes 
care of the complexities of using templates, 
while being completely template agnostic.  
</p> 
<p>This means that you can use any templating language in the exact
same way and get all the additional features that jQuery.View provides.</p>

<h2>Features</h2>
<ul>
	<li>Convenient syntax.</li>
	<li>Template loading from html elements and <b>external files</b>.</li>
	<li>Synchronous and asynchronous template loading.</li>
	<li>Template preloading.</li>
	<li>Caching of processed templates.</li>
	<li>Bundling of processed templates in production builds.</li>
</ul>
<h2>Downloads</h2>
<ul>
	<li>jquery.view.js</li>
	<li>jquery.view.ejs.js</li>
	<li>jquery.view.jaml.js</li>
	<li>jquery.view.micro.js</li>
	<li>jquery.view.tmpl.js</li>
</ul>
<h2>Use</h2> 

<p>
When using views, you're almost always wanting to insert the results of a rendered template into the page.  jQuery.View overwrites the jQuery modifiers so using a view is as easy as:
</p> 

<pre><code>$("#foo").html('mytemplate.ejs',{message: 'hello world'})</code>
</pre> 

<p>
This code:</p> 
<ol>
	<li>
		<p>Loads the template a 'mytemplate.ejs'.  It might look like:</p>
		<pre><code>&lt;h2>&lt;%= message %>&lt;/h2></code></pre>
	</li>
	<li>
		<p>Renders it with {message: 'hello world'}, resulting in:</p>
		<pre><code>"&lt;h2>hello world&lt;/h2>"</code></pre>
	</li>
	<li>
		<p>Inserts the result into the foo element.  Foo might look like:</p>
		<pre><code>&lt;div id='foo'>&lt;h2>hello world&lt;/h2>&lt;/div></code></pre>
	</li>
</ol>



<h3>jQuery Modifiers</h3>
<p>
You can use a template with the following jQuery modifier methods:
</p> 
<table>
	<tr><td><a href='http://api.jquery.com/after/'>after</a> </td><td> <code>$('#bar').after('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/append/'>append</a> </td><td>  <code>$('#bar').append('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/before/'>before</a> </td><td> <code>$('#bar').before('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/html/'>html</a> </td><td> <code>$('#bar').html('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/prepend/'>prepend</a> </td><td> <code>$('#bar').prepend('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/replace/'>replace</a> </td><td> <code>$('#bar').replace('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/replaceWidth/'>replaceWidth</a> </td><td> <code>$('#bar').replaceWidth('temp.jaml',{});</code></td></tr>
	<tr><td><a href='http://api.jquery.com/text/'>text</a> </td><td> <code>$('#bar').text('temp.jaml',{});</code></td></tr>
</table>
<h3>
Template Locations
</h3> 

<p>
View can load from script tags or from files.  To load from a script tag, create a script tag with your template and an id like:
</p> 

<p>
<pre><code>&lt;script type='text/ejs' id='recipes'>
&lt;% for(var i=0; i &lt; recipes.length; i++){ %>
  &lt;li>&lt;%=recipes[i].name %>&lt;/li>
&lt;%} %>
&lt;/script></code></pre>
</p> 

<p>
Render with this template like:
</p> 
<pre><code>$("#foo").html('recipes',recipeData)</code></pre>
<p>Notice we passed the id of the element we want to render.</p>

<h3>Packaging Templates</h3> 
<p>If you're making heavy use of templates, 
you want to organize them in files so they can be reused between pages and
applications.</p>
<p>But, this organization would come at a high price if the browser has 
to retrieve each template individually.  The additional HTTP requests would slow 
down your app.
</p>

<p>
Fortunately, <a href='htttp://stealjs.com'>StealJS</a> can build templates 
into your production files.  
You just have to point to the view file like:
</p> 

<pre><code>steal.views('path/to/the/view.ejs');
</pre></code>
<p>This will pre-process the view and insert it into a compressed single file with
your other JS code.</p>
<p><i>Note:  Steal 1.1 will even let you <b>not</b> load the view engine in 
production if all your templates are packaged.</i></p>
<h3>
Asynchronous
</h3> 

<p>
By default, retrieving requests is done synchronously.  
This is fine because <a href='http://stealjs.com/'>StealJS</a> 
 packages view templates with your JS download.  </p>
<p>
However, some people might not be using StealJS or 
want to delay loading templates until necessary.  
If you have the need, you can provide a callback paramter like:
</p> 


<pre><code>$("#foo").html('recipes',recipeData, function(result){
   this.fadeIn()
});</code></pre>
<p>The callback function will be called with the result of the
rendered template and 'this' will be set to the original jQuery
object.</p>

<h3>
Just Render Templates
</h3> 

<p>
Sometimes, you just want to get the result of a rendered template without inserting it, you can do this with $.View:
</p> 

<pre><code>var out = $.View('path/to/template.jaml',{});
</pre></code>

<h3>Preloading Templates</h3> 

<p>
You can preload templates asynchronously like:
</p> 

<pre><code>$.View('path/to/template.jaml',{}, function(){});</pre></code>
<p>
When it comes time to use them in your app, they will be ready for the user.
</p> 
<h3>
Supported Templates
</h3> 
<p>
JavaScriptMVC comes with the following templates:
</p> 
<ul>
	<li><p>EmbeddedJS</p>
		<pre><code>&lt;h2>&lt;%= message %>&lt;/h2></code></pre></li>
	<li><p>JAML</p>
		<pre><code>h2(data.message);</code></pre></li>
	<li><p>Micro</p>
		<pre><code>&lt;h2>{%= message %}&lt;/h2></code></pre></li>
	<li><p>jQuery.Tmpl</p>
		<pre><code>&lt;h2>${message}&lt;/h2></code></pre></li>
</ul>
<p><a href='http://awardwinningfjords.com/2010/08/09/mustache-for-javascriptmvc-3.html'>Mustache</a> is supported in a 2nd party plugin.

</p>

<h3>
Using Other Templates:
</h3> 

<p>
Integrating into $.View (and StealJS's build process) is easy, you just have to register your script like:
</p> 

<pre><code>$.View.register({
	suffix : "tmpl",
	renderer: function( id, text ) {
		return function(data){
			return jQuery.render( text, data );
		}
	},
	script: function( id, text ) {
		var tmpl = $.tmpl(text).toString();
		return "function(data){return ("+
			tmpl+
			").call(jQuery, jQuery, data); }";
	}
})</pre></code>

<p>
Here's what each property does:</p>
<ul>
	<li><code>suffix</code> - files that use this suffix will be processed by this template engine</li>
	<li><code>renderer</code> - returns a function that will render the template provided by text</li>
	<li><code>script</code> - returns a string form of the processed template function.</li>
</ul>

<h2>Conclusion</h2>
<p>
	Templates are great, but there's a lot of extra work that goes into 
	making a template engine useful.
	But, almost all of that extra work can be abstracted and reused.
</p>
<p> This is exactly what jQuery.View is!  It's a tool so future template 
engines don't have to worry about loading, caching, and bundling templates.</p>
<p>Even better, as it is a uniform template API, it enables plugin authors
to write widgets that accept arbitrary template types.</p>

<p>I personally feel like this would be a good canidate for jQuery an
official jQuery plugin of its own.  Imagine customizing the layout of a 
widget by passing it a template:
   
</p>

<pre><code>$("#upcoming").srchr_search_result({
	modelType : Srchr.Models.Upcoming,
	resultView : "//srchr/views/upcoming.ejs"
});</code></pre>
<p>P.S. This is actual code from our
<a href='http://github.com/jupiterjs/srchr'>JavaScriptMVC version of Srchr</a>.
Read about it <a href='http://jupiterjs.com/news/organizing-a-jquery-application'>here</a>.
We customize search results panels with a Model used to retrieve
searches and a view to output the results.</p>